Fixing Doc Build Warnings #1736
Conversation
|
Before a pull request is accepted, it must meet the following criteria:
|
tardis/scripts/cmfgen2tardis.py
Outdated
|
|
||
|
|
||
| atomic_dataset = AtomData.from_hdf5() | ||
| #atomic_dataset = AtomData.from_hdf() |
There was a problem hiding this comment.
Why is this just commented?
There was a problem hiding this comment.
It doesn't work, I left it as a comment for the same reason as the other one that I just replied to.
There was a problem hiding this comment.
This script is broken into too many levels. Why modifying it right now?
There was a problem hiding this comment.
@epassaro it created a warning
There was a problem hiding this comment.
So this is a broken script. If someone tries to fix it in the future will ask: "why this line is commented?". And that brings confusion.
IMHO I don't think it's a good idea to patch a broken script just to silence a warning.
There was a problem hiding this comment.
I added a comment above the line to explain why it is broken. If we don't comment that part out, it messes up the API as well as defeating the purpose of getting rid of all warnings -- to make it easy to make sure future pull requests don't mess up the docs
Codecov Report
@@ Coverage Diff @@
## master #1736 +/- ##
==========================================
+ Coverage 61.87% 61.88% +0.01%
==========================================
Files 63 63
Lines 5852 5851 -1
==========================================
Hits 3621 3621
+ Misses 2231 2230 -1
Continue to review full report at Codecov.
|
|
One comment, I notice black is currently failing. Fix that and I'll merge. |
* updating installation page * adding debug config page * fixing highlight warnings * making images work * fixing block formatting * fixing docstring for api * removing changelog update instructions * fixing more warnings * deleting scripts docs * formatting index * deleting section also in git_links.inc * putting html_theme_options back in * clearning warnings in cmfgen.py * fixing docstrings for AtomData api * including full file name to exclude ads notebook * explaining why code was commented out * formatting with black
* updating installation page * adding debug config page * fixing highlight warnings * making images work * fixing block formatting * fixing docstring for api * removing changelog update instructions * fixing more warnings * deleting scripts docs * formatting index * deleting section also in git_links.inc * putting html_theme_options back in * clearning warnings in cmfgen.py * fixing docstrings for AtomData api * including full file name to exclude ads notebook * explaining why code was commented out * formatting with black
* updating installation page * adding debug config page * fixing highlight warnings * making images work * fixing block formatting * fixing docstring for api * removing changelog update instructions * fixing more warnings * deleting scripts docs * formatting index * deleting section also in git_links.inc * putting html_theme_options back in * clearning warnings in cmfgen.py * fixing docstrings for AtomData api * including full file name to exclude ads notebook * explaining why code was commented out * formatting with black
* updating installation page * adding debug config page * fixing highlight warnings * making images work * fixing block formatting * fixing docstring for api * removing changelog update instructions * fixing more warnings * deleting scripts docs * formatting index * deleting section also in git_links.inc * putting html_theme_options back in * clearning warnings in cmfgen.py * fixing docstrings for AtomData api * including full file name to exclude ads notebook * explaining why code was commented out * formatting with black
Description
This fixes all but 5 of the remaining documentation build warnings. The other 5 are fixed in #1721.
Most of the changes are very minor and had to do with formatting the documentation and docstrings.
The biggest changes that I should specifically mention are:
docs/scripts/index.rst. It is a duplicate of a section indocs/io/configuration/components/models/index.rst.tardis/scripts/cmfgen2tardis.py. The entire document was already broken and is not being used in the code. I am just preventing errors from occurring when sphinx tries to run the file.logotextkeys in thehtml_theme_optionsdictionary indocs/conf.pyas those keys are not valid.ads.ipynbfrom nbsphinx. Upon merging, I will make a note of this in Improve list of papers using TARDIS #1599.Motivation and context
After the merge of this PR, we will have an easy system to keep our documentation clean -- it will be easy to see if your PR gets sphinx to throw new warnings, and then you can fix them before merging.
How has this been tested?
Examples
Built documentation: https://smithis7.github.io/tardis/branch/warning_fix_doc/index.html
Type of change
Checklist